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Preface 
About Qualys 


Preface 


This user guide is intended for application developers who will use the Qualys CAR API. 


About Qualys 


Qualys, Inc. (NASDAQ: QLYS) is a pioneer and leading provider of cloud-based security and 
compliance solutions. The Qualys Cloud Platform and its integrated apps help businesses 
simplify security operations and lower the cost of compliance by delivering critical 
security intelligence on demand and automating the full spectrum of auditing, 
compliance and protection for IT systems and web applications. 


Founded in 1999, Qualys has established strategic partnerships with leading managed 
service providers and consulting organizations including Accenture, BT, Cognizant 
Technology Solutions, Deutsche Telekom, Fujitsu, HCL, HP Enterprise, IBM, Infosys, NTT, 
Optiv, SecureWorks, Tata Communications, Verizon and Wipro. The company is also a 
founding member of the Cloud Security Alliance (CSA). For more information, please visit 
www.gualys.com. 


Contact Gualys Support 


Oualys is committed to providing you with the most thorough support. Through online 
documentation, telephone help, and direct email support, Oualys ensures that your 
guestions will be answered in the fastest time possible. We support you 7 days a week, 
24 hours a day. Access support information at www.gualys.com/support/. 
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Chapter 1 - Getting Started 


Welcome to Qualys Custom Assessment and Remediation (CAR) APIs. 


Get Started 


Qualys API Framework - Learn the basics about making API requests. The base URL 
depends on the platform where your Qualys account is located. 


Introduction to CAR API Paradigm - Get tips on using the Curl command-line tool to make 
API requests. Every API request must authenticate using a JSON Web Token (JWT) 
obtained from the Qualys Authentication API. 


Get API Notifications 


Subscribe to our API Notifications RSS Feeds for announcements and latest news. 


From our Community 
Join our Community 


API Notifications RSS Feeds 


Qualys API Framework 
The Qualys CAR API uses the following framework. 


Request URL 
The URL for making API requests respects the following structure: 
https://<baseurl>/<module>/<object>/<object_id>/<operation> 


where the components are described below. 


<baseurl> The Qualys API server URL that you should use for API 
requests depends on the platform where your account 
is located. The base URL for Qualys US Platform 1 is: 
https://gateway.gg1.apps.gualys.com 


<module> The API module. For the CAR API, the module is: “sm”. 
<object> The module specific object. 

<object id> (Optional) The module specific object ID, if appropriate. 
<operation> The reguest operation, such as count and search. 


Qualys API URL 


The Qualys API URL you should use for API requests depends on the Qualys platform 
where your account is located. 
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Click here to identify your Qualys platform and get the API URL 


This documentation uses the API gateway URL for Qualys US Platform 1 
(https://gateway.gg1.apps.gualys.com) in sample API requests. If you're on another 
platform, please replace this URL with the appropriate gateway URL for your account. 


Gualys API Postman Collection 


Interact with Oualys APIs using Postman. Instead of creating calls manually to send over 
the command line, you can use the Oualys Postman Collection to get started with Oualys 
APIs guickly. 


Click here to view the steps involved 
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Introduction to CAR API Paradigm 


Authentication 


You must authenticate to the Qualys Cloud Platform using Qualys account credentials 
(user name and password) and get the JSON Web Token (JWT) before you can start using 
the CAR APIs. Use the Qualys Authentication API to get the JWT. 


For example, 


curl -X POST https://gateway.ggl.apps.gualys.com/auth -d 
"username-valuel&password-passwordValue&token-true" -H "Content- 
Type: application/x-www-form-urlencoded" 


where gateway.gg1.apps.gualys.com is the base URL to the Qualys API server where your 
account is located. 


- username and password are the credentials of the user account for which you want to 
fetch CAR data 


- token should be true 
- Content-Type should be "application/x-www-form-urlencoded" 


The Authentication API returns a JSON Web Token WT) which you can use for 
authentication during CAR API calls. The token expires in 4 hours. You must regenerate 
the token to continue using the CAR API. 


Using Curl 


Curl is a multi-platform command-line tool used to transfer data using multiple 
protocols. This tool is supported on many systems, including Windows, Unix, Linux and 
Mac. In this document Curl is used in the examples to build Qualys API requests using the 
HTTP over SSL (https) protocol, which i s required. 


Want to learn more Visit https://curl.haxx.se/ 


The following Curl options are used according to different situations: 


Option Description 

-X GET/POST The GET method or the POST method is used as per reguirement. 

-H 'authorization: This option is used to provide a custom HTTP reguest header parameter 
Bearer <token>' for authentication. Provide the JSON Web Token (JWT) received from 


Qualys authentication API in the following format: 
Authorization: Bearer <token> 
For information about Qualys authentication API, see Authentication. 


-H 'content-type: Denotes that content is in JSON format. 

application/json' 

-d @request.json Provide a request.json file for parameter input. 

--data-urlencode Used to encode spaces and special characters in the URL/Parameter 
values. 
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The sample below shows a typical Curl request using options mentioned above and how 
they interact with each other. 


curl --location --request GET 
'https://gateway.xxx.eng.xxx.gualys.com/sm/vl/scripts/exportids-l 
6515' \ 


--header ‘Authorization: Bearer <authToken>' 
(O' 
Pagination Support for APIs 


CAR APIs are designed to fetch 10 records per page by default. You can use pageSize and 
pageNumber paramaters to fetch more records. 


For example: 
( 


"filter":"status:APPROVED", 


"pageSize":30, 
"pageNumber":0 
} 


Here, 'pageSize' indicates the number of records that should be included in a page. 
'pagenumber' indicates the page number from which records must be fetched. For 
example, "pageNumber":0 would fetch results from page 1. 
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Chapter 2 - Script-based APIs 


Use these API functions to fetch required scripts: 
- Fetch Script Details Based on Script ID or Name 
- List Scripts Based on Script Attributes 


Fetch Script Details Based on Script ID or Name 
[GET] 
sm/v1/scripts/{id} 


Search script details based on the script ID or the script name. 


Response Code 
- 200: Returns the script details output 
- 404: If script with id/name not found 


- 500: Internal server error 


Input Parameters 


{id} as Path parameter (String) Provide Script ID or script name for which you want to fetch 
the details. 


Authorization (String) (Required) Authorization token to authenticate to the Qualys 
Cloud Platform. 
Prepend token with "Bearer" and one space. For example: 
Bearer <authToken> 


Sample 
Request: 


curl--location--request GET 
'https://gateway.xxx.eng.xxx.gualys.com/sm/vl/scripts/16012'M 


--header'Content-Type:application/json'\ 
--header'Authorization:Bearer <authToken>'\ 
--data-raw'' 

Reguest Body: N/A 


Response: 
{ 
"body": { 
Wid" '<SCRIPT IDS, 
"customerUUId":"<CUSTOMER UUID>", 
"title":"<SCRIPT TITLE>", 
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"description":"", 
"category": { 

"rd"; 6; 
"name":"<SCRIPT NAME>" 
DÉI 
"scriptStatus":"APPROVED", 
"importedFromId":0, 
"platform":"WINDOWS", 

"severity":2, 

"threshold":12, 

"type":í( 

"Td"s1, 

"name":"Python" 

DÉI 

"content":"<SCRIPT CONTENT>", 
"recurringDay":0, 

"approverId":"<USER ID OF APPROVER>", 
"approverName":"<USER NAME OF APPROVER>", 
"created": { 

"dateTime":1651846745520, 

"user":{ 

Wid" S"<SEREPLTY LDS, 

"name":"<USER NAME>", 

DÉI 

"updated": { 

"dateTime":1652865043670, 

"user": { 

"id":'"<USER LDS", 

"name":<USER NAME>", 

} 

DÉI 
"LlastExecutedDateTime":1652865043670, 
"hasBlacklistedCommands":true, 


"blacklistedCommands":"os.chmod, wget.download" 
} 
} 


Note: The script content is in base64-encoded format. 
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List Scripts Based on Script Attributes 


[POST] 


/sm/v1/scripts/search 


Search list of scripts for an user account. 


Response Code 
- 200: Returns list of scripts 


- 500: Internal server error 


Input Parameters 


Filter (String) 


Filter the scripts by providing a guery using Oualys syntax. 
Refer to the “How to Search” topic in the online help for 
assistance with creating your guery. 


For example -"filter":"status:DEPRECATED" 


Filter the scripts based on their status. For example: 
Approved, Pending Review, Pending Test, Rejected, 
Deprecated. 


pageNumber (String) 


The page to be returned. Starts from zero. 


pageSize (String) 


The number of records per page to be included in the 
response. Default is 10. 


sort (String) 


Sort the results using a Qualys token. For example: 
[{\"Created.dateTime\":\"asc\"}] 


Authorization (String) 


(Required) Authorization token to authenticate to the Qualys 
Cloud Platform. 
Prepend the token with 'Bearer', followed by a space. For 
example: 

Bearer <authToken> 


Sample 
Request: 


curl --location--reguest POST 'https:// 
gateway.xxx.eng.xxx.gualys.com /sm/vl/scripts/search' \ 
--header 'Content-Type: application/json' \ 

--header 'Authorization: Bearer <authToken>' \ 


--data-raw '( 


"filter":"status:DE 


) Y 


Request Body: 


PRECATED" 


i) Filter scripts with status 'Rejected': 
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Response: 


tion 


"filter":"status:REJECTED" 


"body": 


{ 


"totalCount": 1, 


Wiss s 


[ 


"severity": 


"testAssets": 


1, 


null, 


"importedFromId": 0, 


"approverId": null, 


"created": { 


"dateTime": 


"user": 


"name": 


{ 


"<US 


ER NAME>", 


"id": "<USER ID>" 


} 
), 


"blacklistedCommands": 


"description": 


" 
d 


"lastExecutedDateTime": 


"threshold": 


"title": 
“type: 
"name": 
"id": 4 
), 


{ 


250, 


"<SCRIPT TITL 


1651490591578, 


nw 
, 


0, 


"Powershell", 


"excludedAssets": null 


"assetTags": 


null, 


TY 
E>", 


, 
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"This script is created for Sanity Automa- 
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"platform": "WINDOWS", 
"approverName": null, 
"subscribedModules": [ 
"pc" 

l, 

"schedule": { 
"recurringDay": 0, 
"recurringTime": null, 
"frequency": null 

), 


"customerUuid": "<CUSTOMER UUID>", 


"assets": null, 
"hasBlacklistedCommands": false, 
"id": "72524", 

"category": ( 

"name": "Data Backup", 

“ide X 

), 

"updated": { 

"dateTime": 1651490890451, 


"user": ( 


"name": "<USER NAME>", 


"id": "<USER ID>" 
} 
), 


"status": "REJECTED" 


} 
] 
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Use the following API functions to fetch the asset information: 


- List Assets 


- List Asset Tags 


List Assets 
/sm/v1/assets/search 
[POST] 


Search list of assets on which CAR is enabled. 


Response Code 
- 200: Returns list of assets 


- 500: Internal server error 


Input Parameters 
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Authorization (String) (Required) Authorization token to authenticate to the Qualys 


Cloud Platform. 


Prepend the token with ‘Bearer’, followed by a space. For 


example: 
Bearer <authToken> 
Sample 
Request: 
curl --location --request POST 


'https://gateway.xxx.eng.xxx.gualys.com/sm/vl/assets/search' \ 


--header 'Authorization: Bearer <authToken> 


Response: 
{ 


"errorCode": null, 
"message": null, 


"body": { 
"totalCount": <NUMBER OF ASSETS>, 
"List: |[ 


{ 
"sortValues":[], 
"data":( 
"interfaces": [ 


{ 
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"hostname": "<ASSET NAME>", 
"macAddress":"<MAC ADDRESS>", 
"address":"<ASSET IP>", 


"interfaceName": "eth0" 


, 


{ 

"hostname": 
"macAddress": 
"address": 


null, 


"<MAC ADDRESS>", 


"fe80:0:0:0:82a:39ff:feda:4fa5", 


"interfaceNam 
} 
li 


"address": 


we. "n 


tho" 


"<ASSET IP>", 


"activatedForModules": [ 


" PC" 
E 


"operatingSystem": 
"HOST" e 


"assetType": 
"tags": [ 
12047163, 
11516586, 
8543820, 
9738814 

l; 


"customerUuid": 
<ASSET ID>, 


"assetId": 
"customerId": 


"name": "<ASS 


"agentVersion": 


"id": "<ASSET 
"agentUuid": 
) 

DÉI 

{ 
"sortValues": 
"data": { 
"interfaces": 


{ 


"hostname": 


"macAddress": 
"address": 


"OPERATING SYSTEM", 


"<CUSTOMER UUID>", 


<CUSTOMER ID>, 


ET NAME>", 


"<AGENT 


"<ASSET 


"<CLOUD AGENT VERSION>", 
IP>", 


UUID>" 


"<HOST NAME>", 


"<MAC ADDRESS>", 
IP>", 


"interfaceNam 


), 
{ 


we. "n 


ns160" 
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"hostname": null, 
"macAddress": "<MAC ADDRESS>", 
"address": "<ASSET IP>", 


"interfaceName": "virbr0" 
DÉI 

{ 
"hostname": null, 

"macAddress": "<MAC ADDRESS>", 
"address": "<ASSET IP>", 
"interfaceName": "ens160" 

} 

l, 

"address": "<ASSET IP>", 
"activatedForModules": [ 

"pc" 

li 

"operatingSystem": "<OPERATING SYSTEM", 
"assetType": "HOST", 

"tags": [ 

8543820 

li 

"customerUuid": "<CUSTOMER UUID>", 
"assetId": «ASSET ID», 
"customerId": «CUSTOMER ID», 
"name": "«HOST NAME>", 
"agentVersion": "<AGENT VERSION>", 
"id": "<AGENT ID>", 
"agentUuid": "<AGENT UUID>" 

} 

DÉI 

{ 

"sortValues": [], 

"data": { 

"interfaces": [ 

{ 

"hostname": "<ASSET NAME>", 
"macAddress": "<MAC ADDRESS>", 
"address": "<ASSET IP>", 


I 
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"interfaceName": "Intel(R) PRO/1000 MT Network Connection" 


} 

li 

"address": "KASSET IP>", 

"activatedForModules": [ 
"AGENT FIM", 
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"AGENT PC", 
"FIM" F 
" PC " 


l; 
"operatingSystem": "<OPERATING SYSTEM>", 
"assetType": "HOST", 
"tags": [ 
17970415, 
12047183, 
11172212, 
8546868, 
14695569, 
12047182, 
8543820 


li 

"customerUuid": "2<CUSTOMER UUID>", 
"assetId":<ASSET ID>, 
"customerId": <CUSTOMER ID>, 
"name": "<ASSET NAME>", 
"agentVersion": "<AGENT VERSION>", 
"id": "<AGENT ID>", 
"agentUuid": "<AGENT UUID>" 

) 


List Asset Tags 

/sm/v1/assettags/search 

[POST] 

Search list of asset tags on which CAR is enabled. 


Response Code 
- 200: Returns list of asset tags 


- 500: Internal server error 
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Input Parameters 


Authorization (String) (Required) Authorization token to authenticate to the Qualys 
Cloud Platform. 
Prepend token with ‘Bearer’, followed by a space. For example: 
'Bearer' <authToken> 


Sample 
Reguest: 


curl --location --reguest POST 
'https://gateway.xxx.eng.xxx.gualys.com/sm/vl/assettags/search' 


--header 'Authorization: Bearer <authToken> 


Response: 
{ 


"errorCode": null, 
"message":null, 


"body": { 
"totalCount": <NUMBER OF ASSETS>, 
trist lI 


{ 


"customerUuid": "<CUSTOMER UUID>", 
"tagid": «ASSET TAG», 
"customerId": «CUSTOMER ID», 
"name": "<ASSET NAME>", 

"tagUuid": "<ASSET TAG UUID>", 
"id": "<ASSET ID>" 


"backgroundColor": "#0000FF", 
"customerUuid": "<CUSTOMER UUID>", 
"tagld": <ASSET TAG ID>, 
"customerId": <CUSTOMER ID>, 
"name": "<ASSET TAG>", 

"tagUuid": "<ASSET TAG UUID>", 
"id": "<TAG ID>" 


"customerUuid": "<CUSTOMER UUID>", 
"tagld":<TAG ID», 

"customerId": <CUSTOMER ID>, 
"name": "Internet Facing Assets", 
"tagUuid": "<ASSET TAG UUID>", 
"qd": "<TAG IDS" 


\ 


), 
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ER UUID>", 


( 
"backgroundColor": "#FF0000", 
"customerUuid": "<CUSTOM 
"tagid": «TAG ID», 
"customerId": «CUSTOMER ID», 
"name": "«TAG NAME>", 
"tagUuid": "<ASSET TAG UUID>", 
"id": "«TAG ID»" 


"backgroundColor": "#A2C 
"customerUuid": "«CUSTOM 
"tagid": «TAG ID», 
"customerId": «CUSTOMER 
"name": "<ASSET ID>", 
"tagUuid": "<ASSET TAG U 
"id": "<TAG ID>" 


"customerUuid": "<CUSTOM 
"tagid": «TAG ID», 
"customerId": «CUSTOMER 
"name": "«TAG NAME>", 
"tagUuid": "«ASSET TAG U 
vid TAG ID>" 


"customerUuid": "<CUSTOM 
"tagid": «TAG ID», 
"customerId": «CUSTOMER 
"<TAG NAME>", 
"<ASSET TAG U 


"name": 
"tagUuid": 


"customerUuid": 
"tagid": «TAG ID», 
"customerId": «CUSTOMER 
"name": "«TAG NAME>", 
"tagUuid": "«ASSET TAG U 
"id": "«TAG ID»" 


"backgroundColor": "#FFF 


"customerUuid": 
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4c9", 


ER UUID>", 


ID>, 


UID>", 


ER UUID>", 


ID>, 


UID>", 


ER UUID>", 


ID>, 


UID>"id": 


"<CUSTOMER UUID>", 


ID>, 


UID>", 


FOO", 


"<CUSTOMER UUID>", 


"<TAG ID>" 


"tagid": «TAG ID» 


"customerId": «CUSTOM 


"name": "«TAG NAM 


, 


TY 
E>", 


ER ID>, 


"tagUuid": "<ASSET TAG UUID>", 


"id": "<TAG ID>" 


"backgroundColor" 


: "R206CFF", 


"customerUuid": "<CUSTOMER UUID>", 


"tagid": «TAG ID» 


, 


"customerId": «CUSTOM 


"name": "«TAG NAM 


TY 
E>", 


ER ID>, 


"tagUuid": "<ASSET TAG UUID>", 


"id": "<TAG ID>" 
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Use these API functions to fetch script jobs: 
List Script Jobs 
List Asset Jobs 


List Script Jobs 
/sm/v1/jobs/search 
[POST] 


Search for the parent jobs that are created when you execute scripts. 


Response Code 
- 200: Returns list of jobs 


- 500: Internal server error 


Input Parameters 


Filter (String) Filter the jobs by providing a guery using Oualys syntax. 
Refer to the “How to Search” topic in the online help for 
assistance with creating your guery. 

For example — “scriptld: «SCRIPT ID» 


» 


startAt/endAt Filter jobs based on the time when the jobs are generated 
(dateTime) or the time when the jobs are processed at Qualys 
(processedTime). 

pageNumber (String) The page to be returned. Starts from zero. 

pageSize (String) The number of records per page to be included in the 


response. Default is 10. 


Authorization (String) (Required) Authorization token to authenticate to the Qualys 
Cloud Platform. 
Prepend the token with ‘Bearer’, followed by a space. For 


example: 
Bearer <authToken> 
sort (String) a the results using a Qualys token. For example, ID or 
ategory: 


[{\"Created.dateTime\":\"asc\"}] 
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Sample 
Request: 


curl --location --request POST 
'https://gateway.xxx.eng.xxx.gualys.com/sm/vl/jobs/search' \ 
--header 'Content-Type: application/json' \ 

--header ‘Authorization: Bearer <authToken>' \ 

--data-raw '{ 

"filter":"script.name:Script test for subscribed modules" 

} ' 


Request Body: 


i) Filter jobs using script name 
{ 
"filter":"script.name:Script test for subscribed modules" 
} 


Response: 
{ 


"errorCode": null, 
"message": null, 


"body": { 
"totalCount": 13, 
Wists | 


{ 

"Severity": 2, 

"test": true, 

"created": { 

"dateTime": 1651847969380 

DÉI 

"executionType": "Manual", 

"correlationUuid": "9bde85fb-010e-45fe-8bc0- 
4b55cc6c3a2a", 

"threshold": 12, 

"title": "Script test for subscribed modules- 
1651847969", 

"platform": "WINDOWS", 

"updatedDateTime": 1651847969380, 

"scriptld": 72653, 

"customerUuid": "317df02c-4ad1-55e2-83a3- 
5646a34fceec", 

"isTest": true, 

"scriptType": "Python", 
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“ide 79097", 

"category": ( 
"name": "General Automation", 
midi 6 
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List Asset Jobs 

/sm/v1/assetjobs/search 

[POST] 

The asset job is created per asset when a script is executed on it. 

Note: If you want to include script result in the response, you can set the 
'includeScriptResult' variable to 'True'. 

Response Code 

- 200: Returns list of asset jobs 


- 500: Internal server error 


Input Parameters 


startAt/endAt (String) Filter jobs based on the time when a job is generated 
(dateTime) or based on the time when a job is processed at 
Qualys (processedTime). 


Filter (String) Filter the asset jobs by providing a query using Qualys syntax. 
Refer to the “How to Search” topic in the online help for 
assistance with creating your query. 

For example - "filter": "job.id:<JOB ID>" 


includeScriptResult (String) This flag can be set to 'true' if you want the script output to be 
fetched in the response. 

Note: The script result will be fetched in Base 64 encoded 
format. You must decode it to view the result. 


pageNumber (String) The page to be returned. Starts from zero. 


pageSize (String) The number of records per page to be included in the 
response. Default is 10. 


Authorization (String) (Required) Authorization token to authenticate to the Qualys 
Cloud Platform. 
Prepend token with ‘Bearer’ and one space. For example: 
Bearer <authToken> 


sort (String) Sort the results using a Qualys token. For example, ID, 
Category: 
[{\"Created.dateTime\":\"asc\"}] 


Sample 
Request: 


curl --location --request POST 
'https://gateway.xxx.eng.xxx.qualys.com/sm/vl/assetjobs/search' \ 
--header 'Content-Type: application/json' \ 

--header 'Authorization: Bearer <authToken>' \ 


--data-raw ' 


25 


Chapter 4 - Job-based APIs 


( 
"filter":"job.id:80507", 
"includeScriptResult": true, 
"sort": "[{\"created.dateTime\":\"desc\"}]" 
} ' 

Request Body: 

Search job details with job ID: 


( 
"filter": "job.id:80507", 


"includeScriptResult": true, 


"sort": "[{\"created.dateTime\":\"desc\"}]" 


} 


Response: 
1) Response with the 'IncludeScriptResult variable set to ‘true’: 


Note: The 'scriptResult is in base64-encoded format. 
( 
"errorCode": null, 
"message": null, 
"body": ( 


“bocalCount!": d; 


Desen! 
{ 
"output": { 
"code": 0, 
"text": "SUCCESS" 


DÉI 
"customerUuid": "<CUSTOMER UUID>", 


List Asset Jobs 


"enddate": "2022-05-11T06:42:13.692+00:00", 


"test": false, 


"isTest": false, 


"scriptResult": "U2hlbGwgU2NyaXB0IE91dHBldCBwc- 


mludGVkISEK", 
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"created": { 
"dateTime": 1652251134952 
), 
“id! "80541"; 
“job: 1 


"scriptId": <SCRIPT ID>, 
"ScriptType": "Shell", 
"scriptSeverity": 1, 


"scriptName": "<SCRIPT NAME>", 


"correlationUuid": "<CORRELATION UUID>", 


"id": 80014, 


"platform": "LINUX", 
"ScriptCategory": "Data Backup" 


), 


"asset": { 


"address": "«ASSET IP»", 


"name": "sm-pc-test-Linux-vm2", 


"id": 20452610, 


"agentUuid": "<AGENT UUID>", 


"operatingSystem": "CentOS Linux 7.9.2009", 


"tags": [ 
( 
"name": "Cloud Agent", 
"tagUuid": "<TAG UUID>", 
"id": 102909758 
), 
{ 


"name": "Test tag", 
"tagUuid": "<TAG UUID>", 
"id": 112278818 

), 
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), 


), 


), 


), 


), 


), 
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"name": "SM 1.0 test tag", 
"tagUuid": "<TAG UUID>", 


"id": 120198213 


"name": "SM Tag Test", 
"tagUuid": "<TAG UUID>", 


"id"$ 119295749 


"name": "PostgreSQL", 
"tagUuid": "<TAG UUID>", 


"id": 112207922 


"name": "testBU3", 
"tagUuid": "<TAG UUID>", 


"id": 103100188 


"name": "testBU", 
"tagUuid": "<TAG UUID>", 


"id": 34781853 


"name": "SM"<TAG UUID>", 


"id": 119082623 


"name": "SM 1.1 Tag Test", 
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"tagUuid": "<TAG UUID>", 


"id": 122379045 


Fy 
"manifestId": "c202able-3fbe-46ec-8e28- 


52f644098880", 


"status": "SUCCESS" 
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Chapter 5 - Activity-based APIs 


Use the following API function to fetch activity logs: 
- List Activity Logs 


List Activity Logs 
/sm/v1/scripts/activities 
[POST] 


Search for activities such as create, approve, deprecate, execute, modify, and test carried 
out by CAR users. 


Response Code 
- 200: Returns list of activities/audit logs 


- 500: Internal server error 


Input Parameters 


ggl (String) Filter the activities by providing a guery using Oualys syntax. 
Refer to the “How to Search” topic in the online help for 
assistance with creating your guery. 

For example- "activity: CREATE" 


pageNumber (String) The page to be returned. Starts from zero. 


pageSize (String) The number of records per page to be included in the 
response. The default value is 10. 


sort (String) Sort the results using a Qualys token. For example, ID, 
Category and so on. 
[{\"Created.dateTime\"\"asc\"}] 


startDate, EndDate Provide the start date and the end date to fetch results 
between a specified time frame. 


Sample 


Request: 
1) Filter based on the activity type, such as Create, Approve, Deprecate, Execute, Modify, 
Reject: 


Request: 


curl --location --request POST 


'https:// gateway.xxx.eng.xxx.gualys.com/sm/vl/scripts/activi- 
ties' \ 


--header 'Content-Type: application/json' \ 
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--header 


--data-raw 


TY gal TY s 
} 
Response: 
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"Authorization: Bearer <authToken>' \ 


bat 


"activity: CREATE " 


"auditRecords": [ 


{ 


), 


"id": "a563f016-8ale-46ca-9d5f-f30a5df7f860", 


"auditEnabledAppId": 1, 


"applicationName": "SM", 


"userName": "«USER NAME>", 


"userUuid": "<USER UUID>", 


"customerUuid": "<CUSTOMER UUID>", 


"client": null, 

"sourceIp": null, 
"createdDate": 1651206222012, 
"targetType": "script", 


"targetName": "testFor", 


"action": "CREATE", 


"auditComment": null, 


"externalChangeLink": null, 
"customFields": [ 
( 
"key": "targetId", 


"value": "16016" 
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"totalCount": 1, 
"pageNumber": 0, 
"pageSize": 10, 
"applicationName": "SM", 


"clientApp": "SM", 


"auditEnabledAppId": 1 
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Chapter 6 - Script Operation-based APIs 


Use the following API functions to perform operations on scripts: 
- Export Scripts 

- Import Scripts 

- Clone Scripts 

- Execute Scripts On Demand 


- Schedule Script Execution 


Export Scripts 
sm/v1/scripts/export 
[GET] 


Export one or more scripts by providing script IDs in guery parameter. 
Response Code 


- 200: Exported the scripts 
- 400: Bad reguest (If script is deprecated or rejected) 


- 404: If script not found 


- 500: Internal server error 


Input Parameters 


Authorization (String) (Required) Authorization token to authenticate to the Qualys 
Cloud Platform. 
Prepend the token with "Bearer", followed by a space. For 


example, 
Bearer <authToken> 
IDs as query parameter Provide single or multiple script IDs as the query parameter. 
(Integer) For example: 
https://gate- 
way.xxx.eng.xxx.gualys.com/sm/vl/sc 
ripts/exportids-<SCRIPT 
ID1>,<SCRIPT ID2> 
Sample 
Request: 
curl --location --request GET 
'https://gateway.xxx.eng.xxx.gualys.com/sm/vl/scripts/exportids-16 
5L5T X 
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--header 


'Authorization: 
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Bearer <authToken>' 


You can export multiple scripts by providing multiple comma-separated script IDs. 


For example, https://gateway.xxx.eng.xxx.gualys.com/sm/v1/scripts/export 


ids=72652,75508 


Response: 
[ 


"iq" : 


<SCRIPT ID1>, 


"customerUUId": "<CUS 
"pitten: "<SCRLPT TIT 
"description": "", 
"category": { 

SLAM Dr 


"name": 


), 


"scriptStatus": 


"importedFromId": 0, 
"platform": "WINDOWS" 
"severity": 3, 
"threshold": 50, 


TOMER UUID>", 
E>", 


"System Administration" 


"APPROVED", 


, 


"type": { 
"To, s 
"name": "Python" 
DÉI 
"content": "<SCRIPT CONTENT>", 
"recurringDay": 0, 
"approverId": "«APPROVER ID>", 
"created": { 
"dateTime": 1651745523598, 
"user": { 
"id": "51fbdb4b-5fb5-fdf6-8141-5a7887ec557b", 
"name": "FIM Automation" 


}, 


"updated": { 
"dateTime": 16526 
"user": { 


"lastl 


"id": "51fbdb 


74833932, 


4b-5fb5-fdf6-8141-5a7897ec557b", 


"name": "FIM Automation" 


ExecutedDateTim 


": 1652684748401, 
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"hasBlacklistedCommands": true, 
"blacklistedCommands": "os.chmod, wget.download" 


"id": <SCRIPT ID2>, 
"customerUUId": "<CUSTOMER UUID>", 
"title": "<SCRIPT TITLE>", 
"description": "", 
"category": ( 

mc 5r 

"name": "System Administration" 


DÉI 
"ScriptStatus": "APPROVED", 
"importedFromId": 0, 
"platform": "WINDOWS", 
"Severity": 3, 
"threshold": 50, 
"type": { 

"Tea: di 

"name": "Python" 


DÉI 

"content": "<SCRIPT CONTENT>", 
"recurringDay": O0, 
"approverId": "<APPROVER ID>", 
"approverName": "FIM Automation", 


"created": ( 
"dateTime": 1651748729939, 
"user": ( 
"id": "51fbdb4b-5fb5-fdf6-8141-5a7887ec557b", 
"name": "FIM Automation" 


DÉI 
"updated": { 
"dateTime": 1652674850859, 
"user": { 
"id": "51fbdb4b-5fb5-fdf6-8141-5a7887ec557b", 
"name": "FIM Automation" 


m 

"lastExecutedDateTime": 1652674850859, 
"hasBlacklistedCommands": true, 
"blacklistedCommands": "os.chmod, wget.download" 


}] 
Note: The script content is in base64-encoded format. 
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Import Scripts 

/sm/v1/scripts/import 

[POST] 

Import scripts into CAR. Importing a script only imports the script details and excludes 
the meta data such as asset details. 

Response Code 

- 200: Successfully imported the scripts 


- 409: Conflict(If duplicate script name is present) 


- 429: Too many requests(Maximum script creation limit is reached) 


- 500: Internal server error 


Input Parameters 


File (form-data) option in Browse and select the file to be imported. 
request body. Note: The file must be in .json) format. 
Authorization (String) (Required) Authorization token to authenticate to the Qualys 


Cloud Platform. 
Prepend token with "Bearer", followed by a space. For example, 
Bearer authToken. 


Sample 
Request: 


curl--location-- 
reguestPOST'https://gateway.xxx.eng.xxx.gualys.com/sm/vl/scripts/i 
mport'\ 


--header'Content-Type:multipart/form- 
data;boundary-<calculated when request is sent>'\ 


--header'Authorization:Bearer<authToken>'\ 


form'file=@"/C:/Users/abc/Downloads/ExportedScripts 202205050712.j 
son" ' 


Response: 
{ 


"ImportedIds":"[16508]" 
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Clone Scripts 
/sm/v1/scripts/(scriptld/clone 
[POST] 


Clone a script by using script ID or script name. Even if you clone an approved script, you 
must get it reviewed and approved before you execute it. 


You cannot clone deprecated and rejected scripts. 


Response Code 
- 201: Successfully cloned the script 
- 400: Bad reguest (If script title/description is not in proper format) 


- 404: If script with id/name not found 


- 429: Too many reguests (Maximum script creation limit is reached) 


- 500: Internal server error 


Input Parameters 


Script name/ script ID as Path Name or ID of the script to be cloned. 

parameter 

Authorization (String) Required) Authorization token to authenticate to the Qualys 
Cloud Platform. 
Prepend the token with "Bearer", followed by a space. For 
example, Bearer authToken 

scriptTitle (String) Name of the newly cloned script. 
Note: Duplicate script name is not allowed 

Sample 

Request: 


curl--location-- 
reguestPOST'https://gateway.xxx.eng.xxx.gualys.com/sm/vl/scripts/( 
ScriptId/ScriptName}/clone'\ 


--header'Content-Type:application/json'\ 
--header'Authorization:Bearer <authToken>'\ 
--data-raw' ( 


"scriptTitle":"NewClonedScript" 
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Reguest Body: 


( 
"scriptTitle":"<SCRIPT NAME>" 


) 


Response: 
{ 


"errorCode":"0", 
"message":"Cloned script successfully", 
"body": { 


"id":16520 


Execute Scripts On Demand 
/sm/v1/scripts/{scriptId}/execute 
[POST] 


Execute the script on demand by using script ID. 


Response Code 
- 200: Script execution started successfully 


- 400: Bad request (If script is deprecated OR asset IDs, asset tag IDS not provided OR 
number of asset IDs > 25 OR number of asset tag IDs > 25 OR excluded asset IDs >25) 


- 404: If script with id not found 


- 429: Too many requests (Only one execution allowed within the interval of configured 
time in minutes) 


- 500: Internal server error 
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assetTaglds (String) 


Multiple comma-separated asset tag IDs can be provided. 


testMode (String) 


The script execution through public API is supported only in 
production mode and not in evaluation mode. Hence, this flag 
must always be set to 'false'. 


Authorization (String) 


(Reguired) Authorization token to authenticate to the Oualys 
Cloud Platform. 

Prepend token with "Bearer" and one space. For example, 
Bearer authToken. 


assetlds (String) 


List of asset IDs on which you want to execute the script. 
Multiple comma-separated asset IDs can be provided. 


assetTaglds (String) 


List of asset tag IDs on which on which you want to execute 
the script. 


excludedAssetlds (String) 


Asset IDs on which you do not want the script to be executed. 
Multiple comma-separated asset IDs can be provided. 


Sample 
Request: 


curl --location --request POST 
https://gateway.xxx.eng.xxx.gualys.com/sm/vl/scripts/72648/execute 


\ 


--header 'Content-Type: application/json' \ 
--header ‘Authorization: Bearer <token>' N 


--data-raw '{ 


"testMode": false, 


"assetIds": [ 


"<ASSET ID>" 


l; 
"assetTagIds": 


U, 


"excludedAssetIds": [] 


} Y 


Request Body - Multiple Assets: 


{ 
"testMode": 


"assetlds": 


false, 


[ 


“KASSET ID1>", "<ASSET ID2>","<ASSET ID3>" 


l; 


"assetTagIds": [ 


"<ASSET TAG ID1>","<ASSET TAG ID2>","<ASSET TAG ID3>" 
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"excludedAssetIds": [ 


“KASSET ID1>","<ASSET ID2>","<ASSET ID3>" 


Response: 


"body": ( 


"correlationUuid": "<CORRELATION UUID>" 


) 


Note: Correlation UUID is returned when the script is executed. User can use this as filter 
in reguest body to find the job details using /jobs/search POST API. 


See “List Script Jobs” on page 22. 


Schedule Script Execution 
/sm/v1/scripts/scheduler 
[POST] 


Create a schedule to enable script execution at a specific date and time in future. 
Schedules can be of two types: 


- One-time schedule 

- Recurring schedule 

Notes: 

- StartDate, EndDate, and StartTime are mandatory fields 
- Recurring schedule job can be any of the following: 

-- Hourly 

-- Daily 

-- Weekly 

-- Monthly 


You must have a unique title for the schedule. The following error message is displayed if 
another schedule already exists by the same title: 


“Scheduler with the same title already exists: <Schedule Title>” 
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Response Code 
- 201: Successfully scheduled a script 


- 400: Bad reguest (Assets or Asset tags are empty OR based on configured schedule, the 
given trigger will never fire) 


- 404: If script with id not found 


- 409: Conflict (If duplicate schedule name is present) 


- 500: Internal server error 
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activate (String) 


Activate flag can be set to true if user wants to activate the 
schedule for execution of script. 


Authorization (String) 


(Reguired) Authorization token to authenticate to the Oualys 
Cloud Platform. 

Prepend token with "Bearer" and one space. For example, 
Bearer authToken. 


assetTags: Uuid (String) , ID 
(Integer) 


Provide the agent UUID and the Asset Tag ID. For example: 
[(UUId: "0479cflf-46a8-47ac-af52- 
3984e60f825b", id: 119082623}] 


Assets: UUID (String) , ID 
(Integer) 


Provide the agent UUID and the asset ID. For example: 
[(UUId: "2a44cadf-beea-4ef7-9c5e- 
05639851018f", id: 21094690)] 


Description (String) 


Provide a description for the schedule. 


excludedAssets: UUID (String), 
ID (Integer) 


Asset IDs on which you do not want the script to be executed. 

Multiple comma-separated asset IDs can be provided. 

For example: 
excludedAssets: [(UUId: "322ff7aa- 
cc5a-4674-8201-bfb06bbf2clf", id: 
21789601}] 


Script ID (String) 


The ID of the script to be scheduled for execution. 


Script title (String) 


The title of the script to be executed. 


title (String) 


The title of the schedule. 


user ID (String) 


The customer UUID. 


user name (String) 


Customer's user name. 


endDate (String) 


Last date of the schedule. 


startDate (String) 


Date on which the schedule should start. 


start Time (String) 


Time at which the schedule should start. 


scheduleType (String) 


Recurrence type of the schedule - ONE_TIME, DAILY, HOURLY, 
WEEKLY. 


hourlyInterval (Integer) 


Only applicable to 'Hourly' schedule type. Indicates that the 
script is to be executed with an interval of the specified 
number of hours. 


daysOfWeek (String) 


Applicable only for Weekly’ schedule type. Indicates that the 
script is to be executed with an interval of the specified 
number of days of the week. 


recurrenceDate (Integer) 


Applicable for Monthly’ schedule type. Denotes on which 
date of the month the script is to be executed. 


recurrenceMonth (Integer) 


Applicable for Monthly’ schedule type. Denotes on which 
month of the year the script is to be executed. 


42 


Chapter 6 - Script Operation-based APIs 
Schedule Script Execution 


Sample 
Reguest: 


curl --location --reguest POST 
'https://gateway.xxx.eng.xxx.gualys.com/sm/vl/scripts/scheduler' \ 
--header 'Content-Type: application/json' \ 
--header 'Authorization: Bearer <token>' \ 
--data-raw TI 
"activate": true, 
"assetTags": [], 
"assets": [ 
( 
"UUId": "AGENT UUID>", 
"id": «ASSET ID» 


li 
"description": "", 
"excludedAssets": [], 
"seriptus'": | 
{ 
Vid": «SCRIPT ID», 
"title": "<SCRIPT: TITLES" 


li 

"title": "<SCHEDULE TITLE>", 

"user": { 
"Id: USUSER EDS", 
"name": "«USER NAME>" 


DÉI 
"scheduleType": "ONE TIME" 
"endDate": "2022-05-11", 
"startDate": "2022-05-11", 
“Start Lime: "073725200", 
"scheduleType": "ONE TIME" 


) ' 
Request Body - One-time Schedule: 
( 
"activate": true, 
"assetTags": [], 


"assets": [ 


{ 


"UUId": "<AGENT UUID>", 
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"id": <ASSET ID> 


l; 
"description": "", 
"excludedAssets": [], 


"scripts": [ 


{ 
"id": "<SCRIPT ID>", 
"title": "<SCRIPT TITL 
} 
li 
"title": "SCHEDULE TITLE", 


"user": { 


"id": "<USER ID>", 


"name": "<USER NAME>" 


), 


"endDate": 
"startDate": 
"startTime": 


"2022-05-11", 
"2022-05-11", 
"07:25:00", 


"scheduleType": 


"ONE TIME" 


Request Body - Recurring Monthly Schedule: 


{ 


"activate": true, 
"assetTags": [], 
"assets": [ 


{ 


"UUId": 


"id": "<ASSET ID>" 
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"description": "", 
"excludedAssets": [], 
"scripts": [ 
( 
"idws “<SCRIPT IDS", 


"title": "<SCRIPT TITLE>" 


l; 


"title": "<SCHEDULE TITLE>", 


"user": { 


"id": "<USER ID>", 


"name": "<USER NAME>" 


), 

"endDate": "2022-12-31", 
"startDate": "2022-05-12", 
"startTime": "09:20:00", 


"scheduleType": "MONTHLY", 


"recurrenceDate": 7, 
"recurrenceMonth": 1, 


"monthlyScheduleType": "MONTHLY DATE OF MONTH JOB" 


I 


} 
Request Body - Recurring Weekly Schedule: 


{ 
"activate": true, 
"assetTags": [], 
"assets": [ 


{ 
"UUId": "<AGENT UUID>", 
"id": <ASSET ID> 

), 

{ 
"UUId": "<AGENT UUID>", 
"id": <ASSET ID> 

) 
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"description": "", 
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"excludedAssets": [], 


"scripts": [ 


( 


“id"s <SCRIPT ID»; 
"title": "<SCRIPT TITLE>" 


l; 


"title": "<SCHEDULE 


TITLE>", 


"user": [f 


"id": "<USER ID>", 


"name": "<USER NAME>" 


), 


"endDate": "2022-05-16", 


"startDate": "2022- 


05-11", 


"startTime": "10:49:00", 


"scheduleType": "WE 


EKLY", 


"daysOfWeek": [ 
nq 
DW 


Reguest Body - Recurring Hourly Schedule: 


{ 


"activate": true, 


"assetTags": [], 


"assets": [ 


{ 
"UUId": "<AGENT UUID>", 
"id": <ASSET ID> 
) 
li 
"description": "", 


"excludedAssets": [], 


"Scripts": [ 


{ 


"id": <SCRIPT ID>, 


"title": 


"<SCRIPT TITLE>" 
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l; 


"title": "<SCHEDULE TITLE>", 


"user": { 


mad TEUSER "DS, 


"name": "<USER NAME>" 


), 


"endDate": "2022-05-16", 
"startDate "2022-05-11", 
"startTime": "10:49:00", 


"scheduleType": "HOURLY", 
"hourlyInterval": 6 
} 
Request Body - Recurring Daily Schedule: 
{ 
"activate": false, 
"assetTags": [], 


"assets": [ 


( 
"UUId": "AGENT UUID>", 
"id": "<ASSET ID>" 
} 
li 
"description": "", 


"excludedAssets": [], 
"scripts": [ 
( 
"id" "<SCRIPT IDs", 


"title": "<SCRIPT TITLE>" 


l; 


"title": "<SCHEDULE TITLE>", 
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Response: 


"user": ( 


p»" 


Wid: "USER. ID", 
"name": "<USER NAM 
DÉI 
"endDate": "2022-05-15", 


"startDate": 


"startTime": 


"2022-05-11", 


"09:42:00", 


"scheduleType": "DAILY 


"errorCode": 


"message": 


"body": { 


" 


OM, 


" 
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"Script scheduler created successfully", 


"id": "«Schedule ID»" 
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